The Octopus blog is one of the ways we talk to our customers and help future customers discover Octopus. We do this by publishing posts that resonate with our users (and potential users) on topics of interest to them that demonstrate our domain expertise.
This page provides some tips for writing for the Octopus blog.
We have four main categories that we blog about:
Writing is hard, and we all have different voices, but we want the experience of reading the blog to be consistent and useful. All the posts are edited before they’re published, but the following principles are designed to help guide the voice we use:
The posts we write are useful and informative to our target audience and demonstrate our domain expertise.
We’re direct and honest, and we don’t use hyperbole or marketing-speak.
Our users are educated professionals who prefer directness and honesty so they can decide for themselves if something is useful or interesting. They’re (rightly) suspicious of anything that sounds like marketing-speak, and they want to know the details. We don’t use hyperbole or try to hoodwink people into reading on. This applies throughout every post, but clearly explaining the topic in the opening sentences lets readers decide if they care enough to read on. Even if one topic doesn’t appeal to them, by not wasting their time, they’re more likely to read on the next time they see a post from us that does appeal, however, if we did waste their time, it’s unlikely they’d return at all.
The posts we write have well-defined topics.
After reading one of our posts, we want our readers to feel like they learned something useful. Our posts help readers solve specific problems, tell a story, or otherwise inform them. The better you define your topic and the problem you want to solve before you start writing, the better the chances are your post will be useful, direct, and informative. Having a well-defined topic helps keep us on a direct path from Problem to Solution without wandering off into side stories or anecdotes that don’t directly support the solution being presented.
We’re clear and concise.
We remove the obstacles between the reader and our meaning. This means editing out unnecessary sentences, clauses, and words that don’t directly convey meaning. Often the topics we write about are complicated, and the potential for confusion is high; because of this, we opt for simple sentence structures that don’t place additional cognitive load on the reader.
For instance, the first sentence in this section originally read:
We try to remove as many of the obstacles between the reader and their understanding as we can.
I revised it to:
We remove the obstacles between the reader and our meaning.
There are fewer words to process and trip over in the second version.
Being clear and concise in a first draft is difficult, so sometimes it’s best to get the first draft down, and then go back through the text and delete anything that can be deleted.
A simple rule here is:
If something can be deleted without altering the meaning or tone of the text, it probably should be deleted.
We structure posts logically, so they are easy to follow.
We want our audience to read our posts straight through without needing to go back or read ahead to understand the current point. This can be more work for us, but by structuring our posts in a logical way, we’re not asking more of our readers.
Similar to being clear and concise, it’s not always possible to structure posts in a logical way during the first draft, but that’s okay, after all, it’s only the first draft. If you enjoy working from an outline that can help, but whether you outline or not, it’s worth taking a look at the finished draft to see if you’re asking readers to jump back and forth in the post. If you are, there’s a good chance you need to restructure the post so that things are presented in the order the reader needs to know them.
Just as the entire post should be structured logically, so should the individual sentences in the post. For instance:
Select option A from the User Preferences screen after you’ve logged into the portal.
The above example presents the information in the opposite order than the order the user needs it. Option A is the ultimate goal and so perhaps the most important thing, but the sentence should be changed to guide the user through the process they need to follow without having to read the sentence backward:
After you’ve logged into the portal, click the User Preferences tab, and select option A.
A common structure for our posts looks like this:
Introduction: We state what we’re going to talk about and why it’s useful. Sometimes it’s a good idea to write this after you’ve written the rest of the post when your confidence about what you’re going to say is at its highest.
Body: The body of the post is where you share your hypothesis, how to, or story. If you’re writing a how to post, this is where you explain the steps the reader needs to follow, if you’re explaining a change we’re making to the product, this is where you state the decision we’ve made, explain the reasons for the decision, and tell the reader what to expect next.
Conclusion: Close off the post by restating the main points of the post, share any closing thoughts, and invite feedback.
Include headers that state what each section is about for readers who scan posts or want to jump back to a particular section.
We’re writing for an international audience.
Our customers are everywhere. Some of them are native English speakers, but many of them are not. We avoid colloquialisms that would likely confuse them, and we use US English.
Our posts are written in an informal tone, but we keep the language clear and concise (see above).
We’re not Octo-obsessed.
Octopus isn’t the only thing we write about. We love Octopus, and we hope our users do too, but Octopus isn’t the only tool that can solve our users’ problems, and sometimes, it’s not even the right tool, but that shouldn’t stop us sharing useful content with our users.
No comics or funny Gifs.
Humor is difficult and what might seem like a bit of fun to one reader, can be interpreted a completely different way by other readers. This is a line we don’t need to walk.
For tips on including images, see working with images.